home *** CD-ROM | disk | FTP | other *** search
/ PC World Interactive 7 / PC World Interactive 7.iso / pcgames / EMERGY / DX5SDK / SDK / SAMPLES / MISC / readme.txt
Text File  |  1997-07-14  |  8KB  |  261 lines
  1. DirectX Samples MISC Directory Readme
  2. Copyright (C) 1995-1997 Microsoft Corporation. All Rights Reserved.
  3.  
  4. 1. D3DUtils
  5.  
  6.         d3dutils.h, d3dutils.inl and d3dutils.cpp implement a set
  7. of helper functions for C++ programmers for the following tasks:
  8.  
  9.  
  10. 1a. Matrix construction
  11.  
  12. D3DMATRIX ZeroMatrix();
  13.         Returns the zero matrix.
  14.  
  15. D3DMATRIX IdentityMatrix();
  16.         Returns the identity matrix.
  17.  
  18. D3DMATRIX ProjectionMatrix(const float Zn, const float Zf,
  19.         const float fov);
  20.         Returns the projection matrix:
  21.  
  22.         [c      0       0       0
  23.          0      c       0       0
  24.          0      0       Q       s
  25.          0      0       -QZn    0]
  26.  
  27.                 s = sin(fov/2)
  28.                 c = cos(fov/2)
  29.                 Q = s / (1 - Zn/Zf)
  30.         Zn and Zf specify the near and far clipping planes.
  31.         fov specifies the field of view angle in radians.
  32.  
  33. D3DMATRIX RotateXMatrix(const float rads);
  34. D3DMATRIX RotateYMatrix(const float rads);
  35. D3DMATRIX RotateZMatrix(const float rads);
  36.         Constructs a matrix that rotates about the given axis
  37. by rads radians.
  38.  
  39. D3DMATRIX TranslateMatrix(const float dx, const float dy,
  40.         const float dz);
  41. D3DMATRIX TranslateMatrix(const D3DVECTOR& v);
  42.         Constructs a matrix to translate by the given vector.
  43.  
  44. D3DMATRIX ViewMatrix(const D3DVECTOR& from, const D3DVECTOR& at,
  45.         const D3DVECTOR& up, const float roll);
  46.  
  47.         from is the location of the eye
  48.         at is the location of the eye's point of interest
  49.         up is the global "up" vector
  50.         roll is a roll angle about the axis of the viewer
  51.  
  52.         Constructs a view matrix to translate and rotate such that
  53. the viewer is looking down the +Z axis from the origin.
  54.  
  55. D3DMATRIX ScaleMatrix(const float size);
  56. D3DMATRIX ScaleMatrix(const float a, const float b, const float c);
  57. D3DMATRIX ScaleMatrix(const D3DVECTOR& v);
  58.         Uniform and nonuniform scale matrices.
  59.  
  60. D3DMATRIX MatrixMult (const D3DMATRIX& a, const D3DMATRIX& b);
  61.         Returns a*b
  62.  
  63. D3DMATRIX MatrixInverse (const D3DMATRIX& a);
  64.         Returns the inverse of a.
  65.  
  66. D3DMATRIX MatrixTranspose(const D3DMATRIX& a);
  67.         Returns the transpose of a.
  68.  
  69. D3DVECTOR TransformVector(const D3DVECTOR& v, const D3DMATRIX& m);
  70.         Returns v*m. Divides the result through by the
  71. perspective component of v*m.
  72.  
  73. D3DVECTOR TransformNormal(const D3DVECTOR& v, const D3DMATRIX& m);
  74.         Returns v*MatrixTranspose(MatrixInverse(m)). This is the
  75. correct way to transform a normal vector.
  76.         Note, this routine should not be used to transform batches
  77. of vectors because it would repeatedly perform the transpose and
  78. inverse operations on the input matrix.
  79.  
  80.  
  81. 1b. Light management
  82.  
  83. Data Members
  84.  
  85.         D3DLIGHT2       light;
  86.                 Structure describing the light.
  87.  
  88.         LPDIRECT3DLIGHT lpD3DLight;
  89.                 Interface pointer for the light.
  90.  
  91.         int             changed;
  92.                 Dirty bit for the light.
  93.  
  94. Member Functions
  95.  
  96. HRESULT AddToViewport(LPDIRECT3DVIEWPORT2 lpView);
  97.         Adds the light to the viewport.
  98.  
  99. HRESULT RemoveFromViewport(LPDIRECT3DVIEWPORT2 lpView);
  100.         Removes the light from the viewport.
  101.  
  102. HRESULT Set();
  103.         Forces the light to be updated through SetLight.
  104.  
  105. The Set*/Get* functions enable the application to update the light's
  106. properties with single function calls. The Set* functions set
  107. the dirty bit so the light will be updated when necessary.
  108.  
  109. SetColor/GetColor
  110. SetPosition/GetPosition
  111. SetDirection/GetDirection
  112. SetAttenuation/GetAttenuation
  113. SetRange/GetRange
  114. SetFalloff/GetFalloff
  115. SetUmbra/GetUmbra
  116. SetPenumbra/GetPenumbra
  117. SetFlags/GetFlags
  118.  
  119. Several classes are derived from Light. This is basically to
  120. simplify construction, since some elements of D3DLIGHT2 are
  121. not relevant to certain light types.
  122.  
  123. DirectionalLight(LPDIRECT3D2 lpD3D,
  124.                  const D3DVECTOR& color,
  125.                  const D3DVECTOR& direction);
  126. ParallelPointLight(LPDIRECT3D2 lpD3D,
  127.                    const D3DVECTOR& color,
  128.                    const D3DVECTOR& position);
  129. PointLight(LPDIRECT3D2 lpD3D,
  130.            const D3DVECTOR& color,
  131.            const D3DVECTOR& position);
  132. SpotLight(LPDIRECT3D2 lpD3D,
  133.           const D3DVECTOR& color,
  134.           const D3DVECTOR& position,
  135.           const D3DVECTOR& direction,
  136.           const float umbra_angle,
  137.           const float penumbra_angle);
  138.  
  139. 1c. Material management
  140.  
  141.         The Material class simplifies dealing with Direct3D
  142. materials.
  143.  
  144. Data Members
  145.  
  146.         D3DMATERIAL     Mat;
  147.                 Structure describing the material.
  148.  
  149.         D3DMATERIALHANDLE hMat;
  150.                 The material's handle.
  151.  
  152.     LPDIRECT3DMATERIAL2 lpMat;
  153.                 Pointer to the material's interface.
  154.  
  155.         int             changed;
  156.                 Dirty bit for the material.
  157.  
  158. Member Functions
  159.  
  160. HRESULT SetAsCurrent(LPDIRECT3DDEVICE2 lpDev);
  161.         Sets the material as current to the device.
  162.  
  163. HRESULT SetAsBackground(LPDIRECT3DDEVICE2 lpDev);
  164.         Sets the material as the current background on the device.
  165.  
  166. HRESULT Set(void);
  167.         Forces the material to be updated using SetMaterial.
  168.  
  169. The Set*/Get* functions enable the application to update the various
  170. material properties with single function calls. The Set* functions
  171. set the dirty bit so the material will be updated when necessary.
  172.         SetDiffuse/GetDiffuse
  173.         SetAlpha/GetAlpha
  174.         SetAmbient/GetAmbient
  175.         SetEmissive/GetEmissive
  176.         SetSpecular/GetSpecular
  177.         SetPower/GetPower
  178.         SetRampSize/GetRampSize
  179.         SetTextureHandle/GetTextureHandle
  180.  
  181. See boids and pplane for examples of how to use the Material class.
  182.  
  183. 2. D3DTexture
  184.  
  185.         d3dtex.h and d3dtex.cpp implement the D3DTexture class, which
  186. simplifies texture managment.  D3DTexture's features are as follows:
  187.         - Keeps a system memory copy of the texture to restore the surface.
  188.         - Enables loading textures from bitmaps
  189.         - Uses DirectDraw's GetDC function to access GDI's support
  190.           for color-converting blts to load the textures.
  191.           Note, D3DTexture does not currently support textures with
  192.           alpha because GDI does not support bitmaps with alpha.
  193.  
  194.         See boids and flip3d for examples of how to use D3DTexture.
  195.  
  196.  
  197. 3.  GetDXVersion
  198.  
  199.     getdxver.cpp implements sample code showing how to detect which
  200. version of DirectX is currently running (1.0, 2.0, ..., 5.0).
  201.  
  202.         See boids and flip3d for examples of how to use GetDXVersion.
  203.        
  204.  
  205. 4.1 RMMain
  206.  
  207. Uses D3DRM to setup a window for rendering, ask the sample to build
  208. it's scene and then renders the scene.
  209.  
  210. rmmain.cpp
  211.  
  212. Main source file which includes WinMain and message handler.  Creates
  213. D3DRM, uses it to setup the window for rendering and then asks the
  214. sample to build it's scene.
  215.  
  216. rmmain.h
  217.  
  218. Header for rmmain.cpp.
  219.  
  220. rmmain.rc
  221.  
  222. Resource file for rmmain.cpp.
  223.  
  224. rmerror.cpp
  225.  
  226. D3DRM error code to string and error message box.
  227.  
  228. rmerror.h
  229.  
  230. Header for rmerror.cpp.
  231.  
  232. rmdemo.h
  233.  
  234. Because the samples do not create and manage all DirectDraw and
  235. Direct3D objects themselves, the source is much simpler than the
  236. immediate mode samples, but they can only run in a window.
  237. Optionally, the D3DRM samples can be linked to D3DApp via another
  238. harness.  This will allow them to enter fullscreen modes.  Fly is
  239. linked to these files.
  240.  
  241. rmfull.cpp
  242.  
  243. Main source file which includes WinMain and message handler.  Uses
  244. D3DApp to setup rendering.
  245.  
  246. rmfull.h
  247.  
  248. Header for rmfull.cpp.
  249.  
  250. rmfull.rc
  251.  
  252. Defines menus and keyboard accelerator.
  253.  
  254. rmfullrc.h
  255.  
  256. Header for rmfull.rc.
  257.  
  258. rmstats.cpp
  259.  
  260. Calculates and displays frame rate and other information.
  261.